Fetch Company and LLP Master Data API - v1

This document highlights the Fetch Fetch Company and LLP Master Data API - v1 details.

API Description

Objective

The Fetch Company and LLP Master Data API - v1 authenticates the Company Identity Number(CIN), Limited Liability Partnership Identification Number(LLPIN), Foreign Company Registration Number(FCRN) and Foreign Limited Liability Partnership Identification Numbers (FLLPIN) issued by the Ministry of Corporate Affairs (MCA) and retrieves the master data associated with it.

Input	Output
The unique CIN, LLPIN, FCRN or FLLPIN	The master data of the company or the Limited Liability Partnership(LLP) associated with the identity number

API URL

fetchCINDetails

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and ﬁles as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	Application ID shared by HyperVerge	N/A. This is a unique value.
appKey	Mandatory	Application Key shared by HyperVerge	N/A. This is a unique value.
transactionId	Mandatory	Unique ID for the customer journey.	N/A. Any defined unique value mapped to a transaction in your business ecosystem.

Inputs

The following table provides the details of the parameters required for the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
`id`	The twenty-one characters alphanumeric unique identification code allotted by the central government to each company or the seven characters alphanumeric unique identification code issued to an LLP	Mandatory	Not Applicable	Not Applicable
`consent`	The parameter value should be set to 'Y' in the request	Mandatory	Not Applicable	Not Applicable
`reason`	A valid reason for the purpose of verification. Minimum length: 20 characters	Mandatory	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/fetchCINDetails' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "id": "<Enter_the_unique_ID>",
    "consent": "<Enter_Y_or_N>",
    "reason": "<Enter_the_valid_reason>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
 "status": "success",
  "statusCode": "200",
  "result": {
    "code": 200,
    "data": {
      "company_master_data": {
        "company_category": "<company_category>",
        "email_id": "<email_id>",
        "class_of_company": "<class_of_company>",
        "date_of_last_agm": "<date_of_last_agm>",
        "registered_address": "<registered_address>",
        "registration_number": "<registration_number>",
        "paid_up_capital(rs)": "<paid_up_capital>",
        "whether_listed_or_not": "<whether_listed_or_not>",
        "suspended_at_stock_exchange": "<suspended_at_stock_exchange>",
        "cin": "<cin>",
        "company_subcategory": "<company_subcategory>",
        "authorised_capital(rs)": "<authorised_capital>",
        "company_status(for_efiling)": "<company_status>",
        "roc_code": "<roc_code>",
        "date_of_balance_sheet": "<date_of_balance_sheet>",
        "date_of_incorporation": "<date_of_incorporation>",
        "company_name": "<company_name>",
        "active_compliance": "<active_compliance>",
        "rd_region": "<rd_region>",
        "balance_sheets": [],
        "annual_returns": []
      },
      "charges": [
        {
          "date_of_creation": "<date_of_creation>",
          "date_of_modification": "<date_of_modification>",
          "charge_amount": "<charge_amount>",
          "status": "<status>"
        }
         // Other charge entries follow the same structure
      ],
      "directors/signatory_details": [
        {
          "end_date": "<end_date>",
          "din/pan": "<din/pan>",
          "designation": "<designation>",
          "begin_date": "<begin_date>",
          "name": "<name>"
        }
        // Other director/signatory details follow the same structure
      ]
    }
  },
  "metaData": {
    "requestId": "<Request_Id>"
  }
}

Success Response Details

The following table outlines the details of the success response from the API:

Field Name	Type	Description
status	String	Indicates whether the request was successful. Expected value: "success".
statusCode	String	The HTTP status code. Expected value: "200".
result	Object	Contains the detailed response data.
company_category	String	The category of the company (e.g., "Company limited by shares").
email_id	String	The registered email ID of the company.
class_of_company	String	The classification of the company (e.g., "Public").
date_of_last_agm	String	Date of the last Annual General Meeting (AGM).
charges	Array	A list of charges associated with the company.
charges.charge_id	String	The unique identifier for the charge.
charges.charge_amount	String	The amount associated with the charge.
charges.charge_date	String	The date on which the charge was created.
charges.charge_status	String	The current status of the charge.
directors	Array	A list of directors associated with the company.
directors.director_id	String	The unique identifier of the director.
directors.director_name	String	The full name of the director.
directors.date_of_appointment	String	The date the director was appointed.
signatory_details	Array	A list of signatories associated with the company.
signatory_details.signatory_id	String	The unique identifier of the signatory.
signatory_details.signatory_name	String	The full name of the signatory.
signatory_details.signatory_designation	String	The designation of the signatory.

Failure Response

The following code snippet shows a failure response from the API.

{
  "status": "failure",
  "statusCode": "422",
  "error": {
    "transaction_id": "<Transaction_ID>",
    "code": 422,
    "message": "Entered CIN/LLPIN/FLLPIN/FCRN is not found. Please enter valid details.",
    "timestamp": <Time_Stamp>
  }
}

Error Response

The following code snippets show the error responses from the API.

Missing Consent
Invalid Pattern

{
  "status": "failure",
  "statusCode": "422",
  "error": {
  "message": "Invalid parameter: Consent is required.",
  "timestamp": <Time_Stamp>
  },
  "metaData": {
  "requestId": "<Request_ID>"
  }
}

{
"status": "failure",
"statusCode": "422",
"error": {
"message": "Entered CIN/LLPIN/FLLPIN/FCRN is not found. Please enter valid details.",
"timestamp": <Time_Stamp>
},
"metaData": {
"requestId": "<Request_ID>"
}
}

Failure and Error Response Details

Error Codes	Error Message	Error Description
422	Invalid parameter: Consent is required.	The request does not have the mandatory consent parameter
422	Entered CIN/LLPIN/FLLPIN/FCRN is not found. Please enter valid details info CIN/FCRN/LLPIN/FLLPIN must be of the pattern [ADDDDDAADDDDAAADDDDDD] for CIN, [FDDDDD] for FCRN, [AAA-DDDD] for LLPIN and [FAAA-DDDD] for FLLPIN where A is an alphabet, D is a digit (0-9) and F is a literal F	Kindly check the format of the id input in the request
422	No Relation data exists for the entered DIN	The API failed to retrieve any information against the DIN input
500	Internal Server Error	Please contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Inputs​

Request​

Success Response​

Success Response Details​

Failure Response​

Error Response​

Failure and Error Response Details​